Skip loading clerk-ui when headless variants are used #7570

nikosdouvlis · 2026-01-09T11:34:16Z

Description

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

Summary by CodeRabbit

New Features
- Adds headless variant support across Next.js, Astro, React, and Vue so the app can load only the Clerk JS core (no UI) when configured via environment variable.
Tests
- Added an integration test verifying headless variant behavior and that only the core Clerk script is injected.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

why: when using clerkJSVariant='headless', applications only need control components and don't require the full UI bundle. loading the unnecessary @clerk/ui script adds overhead without providing value. what changed: - clerk-script.tsx: conditionally render clerk-ui script tag only when clerkJSVariant !== 'headless' - integration template: read NEXT_PUBLIC_CLERK_JS_VARIANT env var and pass to ClerkProvider users can now set NEXT_PUBLIC_CLERK_JS_VARIANT='headless' to skip loading the ~100KB @clerk/ui bundle when using only control components.

why: when using clerkJSVariant='headless', applications only need control components and don't require the full UI bundle. loading the unnecessary @clerk/ui script adds overhead without providing value. what changed: - build-clerk-hotload-script: skip generating clerk-ui script tag when clerkJsVariant === 'headless' - create-clerk-instance: getClerkUiEntryChunk returns undefined for headless variant to skip client-side hot-loading users can now set clerkJSVariant='headless' to skip loading the ~100KB @clerk/ui bundle when using only control components.

why: when using clerkJSVariant='headless', applications only need control components and don't require the full UI bundle. loading the unnecessary @clerk/ui script adds overhead without providing value. what changed: isomorphicClerk's getClerkUiEntryChunk method now returns undefined when clerkJSVariant === 'headless', skipping the loadClerkUiScript call entirely. users can now set clerkJSVariant='headless' to skip loading the ~100KB @clerk/ui bundle when using only control components.

why: when using clerkJSVariant='headless', applications only need control components and don't require the full UI bundle. loading the unnecessary @clerk/ui script adds overhead without providing value. what changed: clerkPlugin now checks if clerkJSVariant === 'headless' and skips the loadClerkUiScript call, resolving the clerkUiCtorPromise to undefined instead. users can now set clerkJSVariant='headless' to skip loading the ~100KB @clerk/ui bundle when using only control components.

why: verify that the headless variant correctly skips clerk-ui script injection across the full integration stack (env var → prop → script rendering). what changed: created headless-variant.test.ts that sets CLERK_JS_VARIANT='headless' and asserts clerk-ui script is absent while clerk-js script is present.

changeset-bot · 2026-01-09T11:34:21Z

🦋 Changeset detected

Latest commit: 294bc54

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel · 2026-01-09T11:34:21Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jan 12, 2026 10:48am

pkg-pr-new · 2026-01-09T11:37:25Z

Open in StackBlitz

@clerk/agent-toolkit

npm i https://pkg.pr.new/@clerk/agent-toolkit@7570

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@7570

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@7570

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@7570

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@7570

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@7570

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@7570

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@7570

@clerk/express

npm i https://pkg.pr.new/@clerk/express@7570

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@7570

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@7570

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@7570

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@7570

@clerk/react

npm i https://pkg.pr.new/@clerk/react@7570

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@7570

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@7570

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@7570

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@7570

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@7570

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@7570

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@7570

commit: 294bc54

coderabbitai · 2026-01-09T11:37:31Z

📝 Walkthrough

Walkthrough

Adds handling for a clerkJSVariant set to 'headless' across Next.js, Astro, React, and Vue packages. When clerkJSVariant === 'headless', the codepath skips loading or returning the Clerk UI constructor and omits the Clerk UI script, while still loading the core Clerk JS. A new integration test verifies that the Clerk JS script is injected and the Clerk UI script is not when headless mode is enabled.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main objective of the PR: skipping clerk-ui bundle loading when headless variants are configured. It is clear, concise, and directly reflects the primary changes across all modified files.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

📜 Recent review details

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between a2e16cd and 294bc54.

⛔ Files ignored due to path filters (1)

pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (1)

.changeset/light-eagles-stay.md

✅ Files skipped from review due to trivial changes (1)

.changeset/light-eagles-stay.md

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (25)

GitHub Check: Integration Tests (nextjs, chrome, 16, RQ)
GitHub Check: Integration Tests (react-router, chrome)
GitHub Check: Integration Tests (custom, chrome)
GitHub Check: Integration Tests (astro, chrome)
GitHub Check: Integration Tests (vue, chrome)
GitHub Check: Integration Tests (machine, chrome, RQ)
GitHub Check: Integration Tests (nextjs, chrome, 15)
GitHub Check: Integration Tests (nextjs, chrome, 16)
GitHub Check: Integration Tests (billing, chrome, RQ)
GitHub Check: Integration Tests (express, chrome)
GitHub Check: Integration Tests (handshake:staging, chrome)
GitHub Check: Integration Tests (handshake, chrome)
GitHub Check: Integration Tests (localhost, chrome)
GitHub Check: Integration Tests (nuxt, chrome)
GitHub Check: Integration Tests (generic, chrome)
GitHub Check: Integration Tests (ap-flows, chrome)
GitHub Check: Integration Tests (quickstart, chrome, 16)
GitHub Check: Integration Tests (quickstart, chrome, 15)
GitHub Check: Integration Tests (sessions:staging, chrome)
GitHub Check: Integration Tests (machine, chrome)
GitHub Check: Integration Tests (billing, chrome)
GitHub Check: Integration Tests (sessions, chrome)
GitHub Check: Integration Tests (tanstack-react-start, chrome)
GitHub Check: Analyze (javascript-typescript)
GitHub Check: semgrep-cloud-platform/scan

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

nikosdouvlis added 5 commits January 9, 2026 13:15

github-actions bot added nextjs react integration astro vue core-3 labels Jan 9, 2026

nikosdouvlis added 2 commits January 12, 2026 12:36

Merge branch 'main' into nikos/dont-load-clerk-ui-if-headless-is-used

9d3bbe6

dedupe

294bc54

vercel bot deployed to Preview January 12, 2026 10:48 View deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Skip loading clerk-ui when headless variants are used #7570

Skip loading clerk-ui when headless variants are used #7570

nikosdouvlis commented Jan 9, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

changeset-bot bot commented Jan 9, 2026 •

edited

Loading

Uh oh!

vercel bot commented Jan 9, 2026 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Jan 9, 2026 •

edited

Loading

Uh oh!

coderabbitai bot commented Jan 9, 2026 •

edited

Loading

Walkthrough

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Skip loading clerk-ui when headless variants are used #7570

Are you sure you want to change the base?

Skip loading clerk-ui when headless variants are used #7570

Conversation

nikosdouvlis commented Jan 9, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Type of change

Summary by CodeRabbit

Uh oh!

changeset-bot bot commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel bot commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new bot commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai bot commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

nikosdouvlis commented Jan 9, 2026 •

edited by coderabbitai bot

Loading

changeset-bot bot commented Jan 9, 2026 •

edited

Loading

vercel bot commented Jan 9, 2026 •

edited

Loading

pkg-pr-new bot commented Jan 9, 2026 •

edited

Loading

coderabbitai bot commented Jan 9, 2026 •

edited

Loading